HAL I3C Types

HAL I3C Types

STM32C562xx STM32C5A3xx STM32C542xx

group I3C_Exported_Types

Typedefs

typedef struct hal_i3c_handle_s hal_i3c_handle_t

I3C handle structure type

typedef void ( * hal_i3c_cb_t ) ( hal_i3c_handle_t * hi3c )

Pointer to an I3C callback function.

typedef void ( * hal_i3c_notify_cb_t ) ( hal_i3c_handle_t * hi3c , uint32_t notify_id )

Pointer to an I3C notification callback function.

typedef void ( * hal_i3c_tgt_hot_join_cb_t ) ( hal_i3c_handle_t * hi3c , uint8_t dynamic_address )

Pointer to an I3C target Hot-Join callback function.

typedef void ( * hal_i3c_req_dyn_addr_cb_t ) ( hal_i3c_handle_t * hi3c , uint64_t target_payload )

Pointer to a target request dynamic address I3C callback function.

Enums

enum hal_i3c_mode_t

Communication role (none / Controller / Target).

Values:

enumerator HAL_I3C_MODE_NONE

No I3C communication ongoing

enumerator HAL_I3C_MODE_CTRL

I3C communication is in controller Mode

enumerator HAL_I3C_MODE_TGT

I3C communication is in target Mode

enum hal_i3c_state_t

State structure definition.

Values:

enumerator HAL_I3C_STATE_RESET

Not yet Initialized

enumerator HAL_I3C_STATE_INIT

I3C is initialized but not yet configured

enumerator HAL_I3C_STATE_IDLE

I3C initialized and a global config applied

enumerator HAL_I3C_STATE_TX

Data transmission process is ongoing

enumerator HAL_I3C_STATE_RX

Data reception process is ongoing

enumerator HAL_I3C_STATE_TX_RX

Data multiple Transfer process is ongoing

enumerator HAL_I3C_STATE_DAA

Dynamic address assignment process is ongoing

enumerator HAL_I3C_STATE_TGT_REQ

Target request process is ongoing

enumerator HAL_I3C_STATE_ABORT

Abort user request is ongoing

enum hal_i3c_transfer_mode_t

Bitfield encoding message type, stop/restart policy, arbitration header & defining byte. HAL I3C mode value coding follow below described bitmap: b31 0: message end type restart 1: message end type stop (I3C_CR_MEND / LL_I3C_GENERATE_STOP) b30-b29-b28-b27 0010: Private I3C message (I3C_CR_MTYPE_1 / LL_I3C_CONTROLLER_MTYPE_PRIVATE) 0100: Private I2C message (I3C_CR_MTYPE_2 / LL_I3C_CONTROLLER_MTYPE_LEGACY_I2C) 0011: CCC direct message (I3C_CR_MTYPE_1 | I3C_CR_MTYPE_0 / LL_I3C_CONTROLLER_MTYPE_DIRECT) 0110: CCC broadcast message (I3C_CR_MTYPE_2 | I3C_CR_MTYPE_1 / LL_I3C_CONTROLLER_MTYPE_CCC) b2 1: message without arbitration header (I3C_CFGR_NOARBH) 0: message with arbitration header b0 0: message without defining byte 1: message with defining byte (LL_I3C_DEFINE_BYTE)

other bits (not used).

Values:

enumerator HAL_I3C_PRIVATE_WITH_ARB_RESTART

Restart between each I3C private message then Stop request for last message.

enumerator HAL_I3C_PRIVATE_WITH_ARB_STOP

Stop between each I3C private message. Each message start with an arbitration header after start bit condition.

enumerator HAL_I3C_PRIVATE_WITHOUT_ARB_RESTART

Restart between each I3C message then stop request for last message. Each message start with target address after start bit condition.

enumerator HAL_I3C_PRIVATE_WITHOUT_ARB_STOP

Stop between each I3C private message. Each message start with target address after start bit condition.

enumerator HAL_I2C_PRIVATE_WITH_ARB_RESTART

Restart between each I2C private message then stop request for last message. Each message start with an arbitration header after start bit condition.

enumerator HAL_I2C_PRIVATE_WITH_ARB_STOP

Stop between each I2C private message. Each message start with an arbitration header after start bit condition.

enumerator HAL_I2C_PRIVATE_WITHOUT_ARB_RESTART

Restart between each I2C message then stop request for last message. Each message start with target address after start bit condition.

enumerator HAL_I2C_PRIVATE_WITHOUT_ARB_STOP

Stop between each I2C private message. Each message start with target address after start bit condition.

enumerator HAL_I3C_CCC_DIRECT_WITH_DEFBYTE_RESTART

Restart between each direct command then stop request for last command. Each command has an associated defining byte

enumerator HAL_I3C_CCC_DIRECT_WITH_DEFBYTE_STOP

Stop between each direct command. Each command has an associated defining byte.

enumerator HAL_I3C_CCC_DIRECT_WITHOUT_DEFBYTE_RESTART

Restart between each direct command then stop request for last command. Each command does not have an associated defining byte.

enumerator HAL_I3C_CCC_DIRECT_WITHOUT_DEFBYTE_STOP

Stop between each direct command. Each command does not have an associated defining byte.

enumerator HAL_I3C_CCC_BROADCAST_WITH_DEFBYTE_RESTART

Restart between each broadcast command then stop request for last command. Each command has an associated defining byte.

enumerator HAL_I3C_CCC_BROADCAST_WITH_DEFBYTE_STOP

Stop between each broadcast command. Each command has an associated defining byte.

enumerator HAL_I3C_CCC_BROADCAST_WITHOUT_DEFBYTE_RESTART

Restart between each broadcast command then stop request for last command. Each command does not have an associated defining byte.

enumerator HAL_I3C_CCC_BROADCAST_WITHOUT_DEFBYTE_STOP

Stop between each broadcast command. Each command does not have an associated defining byte.

enum hal_i3c_dyn_addr_opt_t

Strategy used by Controller to (re)enumerate dynamic addresses.

Selects how the controller manages dynamic address distribution:

• RSTDAA+ENTDAA: full reset of any previously assigned dynamic addresses followed by a fresh enumeration (use after topology changes or suspected collisions).

• ENTDAA only: perform enumeration assuming no stale dynamic addresses are present (faster startup on a clean bus or after global reset).

Values:

enumerator HAL_I3C_DYN_ADDR_RSTDAA_THEN_ENTDAA

Full re-enumeration: issue RSTDAA to clear all dynamic addresses then run ENTDAA to assign new ones. Ensures a clean address map.

enumerator HAL_I3C_DYN_ADDR_ONLY_ENTDAA

Quick enumeration: run ENTDAA directly. Use when bus is known to be in pristine state (e.g. initial power-up) to save time.

enum hal_i3c_pattern_opt_t

Special bus patterns (reset, HDR exit) emitted by controller.

Patterns are special electrical/sequence encodings placed on the bus outside normal frame transfers. They are used to signal global state changes:

• Target Reset: issues a bus-level reset indication recognized by compliant targets.

• HDR Exit: transitions all devices from High Data Rate mode back to Standard Data Rate (SDR).

Values:

enumerator HAL_I3C_PATTERN_TGT_RESET

Inject reset pattern to request targets reinitialize transient state.

enumerator HAL_I3C_PATTERN_HDR_EXIT

Inject exit pattern to terminate HDR mode and restore SDR signaling.

enum hal_i3c_direction_t

Data phase direction (controller write or read).

Values:

enumerator HAL_I3C_DIRECTION_WRITE

Write transfer Controller sends data bytes to the addressed target

enumerator HAL_I3C_DIRECTION_READ

0x00010000 Read Not Write Read transfer Controller receives data bytes from the addressed target

enum hal_i3c_rx_fifo_threshold_t

Rx FIFO service granularity (byte vs word trigger level).

The Rx FIFO size is 8 bytes (2 words) and an interrupt is generated while it is not empty. The selected threshold guides whether Software/DMA reads the FIFO one byte at a time or one word at a time. Advantages:

• 1/8 (1 bytes threshold / 8 bytes FIFO): minimal read latency; finer flow control; better for short or sporadic transfers; simpler handling when parsing variable-length headers.

• 1/2 (1 word threshold / 2 words FIFO): fewer service events (lower CPU/IRQ/DMA overhead); higher effective throughput on long bursts; improved bus efficiency when payload size is large. Choose based on latency sensitivity versus servicing overhead.

Values:

enumerator HAL_I3C_RX_FIFO_THRESHOLD_1_8

Rx FIFO threshold is 1 byte in a FIFO depth of 8 bytes 1 byte threshold / 8 bytes FIFO. Software/DMA reads byte while Rx FIFO is not empty.

enumerator HAL_I3C_RX_FIFO_THRESHOLD_1_2

0x00000400 RX FIFO Threshold Rx FIFO threshold is 1 word in a FIFO depth of 2 word 1 word threshold / 2 words FIFO. Software/DMA reads word while Rx FIFO is not empty.

enum hal_i3c_tx_fifo_threshold_t

Tx FIFO service granularity (byte vs word trigger level).

The Tx FIFO size is 8 bytes (2 words) and an interrupt is generated while the Tx FIFO is not full. The selected threshold guides whether Software/DMA writes the FIFO one byte at a time or one word at a time. Advantages:

• 1/8 (1 bytes threshold / 8 bytes FIFO): minimal read latency; finer flow control; better for short or sporadic transfers; simpler handling when parsing variable-length headers.

• 1/2 (1 word threshold / 2 words FIFO): fewer service events (lower CPU/IRQ/DMA overhead); higher effective throughput on long bursts; improved bus efficiency when payload size is large. Choose based on latency sensitivity versus servicing overhead.

Values:

enumerator HAL_I3C_TX_FIFO_THRESHOLD_1_8

Tx FIFO threshold is 1 byte in a FIFO depth of 8 bytes 1 byte threshold / 8 bytes FIFO. Software/DMA writes byte while Tx FIFO is not full.

enumerator HAL_I3C_TX_FIFO_THRESHOLD_1_2

0x00004000 TX FIFO Threshold Tx FIFO threshold is 1 word in a FIFO depth of 2 words 1 word threshold / 2 words FIFO. Software/DMA writes word while Tx FIFO is not full.

enum hal_i3c_ctrl_fifo_t

Selection of Transmit Control (TC) and Receive Status (RS) FIFOs activation.

Values:

enumerator HAL_I3C_CTRL_FIFO_NONE

Control and status FIFO disable Transmit Control (TC) and Receive Status (RS) FIFOs are disabled

enumerator HAL_I3C_CTRL_FIFO_CONTROL_ONLY

0x00080000 Control FIFO mode Enable Control FIFO enable Enable Transmit Control (TC) to queue control words to be transmitted

enumerator HAL_I3C_CTRL_FIFO_STATUS_ONLY

0x00040000 Status FIFO mode Enable Status FIFO enable Enable Receive Status (RS) FIFO to capture status words received

enumerator HAL_I3C_CTRL_FIFO_ALL

Control and status FIFO enable Both TC and RS FIFOs are enabled

enum hal_i3c_control_fifo_status_t

Control FIFO (C-FIFO) Status.

Values:

enumerator HAL_I3C_CONTROL_FIFO_DISABLED

Control FIFO is disabled

enumerator HAL_I3C_CONTROL_FIFO_ENABLED

Control FIFO is enabled

enum hal_i3c_status_fifo_status_t

Status FIFO (S-FIFO) Status.

Values:

enumerator HAL_I3C_STATUS_FIFO_DISABLED

Status FIFO is disabled

enumerator HAL_I3C_STATUS_FIFO_ENABLED

Status FIFO is enabled

enum hal_i3c_tgt_payload_size_t

Number of data bytes appended after IBI acknowledge.

Specifies how many data bytes follow the IBI acknowledge phase when a target asserts an In-Band Interrupt. These bytes typically convey a cause code, sensor snapshot or status flags allowing the initiator to react without issuing a separate read. Selecting the minimal size reduces bus occupancy; larger payloads allow richer contextual information at the cost of a few extra cycles.

Values:

enumerator HAL_I3C_TGT_PAYLOAD_EMPTY

Empty payload, no additional data after IBI ack Empty payload, no additional data after IBI acknowledge

enumerator HAL_I3C_TGT_PAYLOAD_1_BYTE

0x00010000 1 additional data byte after IBI ack 1 additional data byte after IBI acknowledge

enumerator HAL_I3C_TGT_PAYLOAD_2_BYTE

0x00020000 2 additional data bytes after IBI ack 2 additional data bytes after IBI acknowledge

enumerator HAL_I3C_TGT_PAYLOAD_3_BYTE

3 additional data bytes after IBI ack 3 additional data bytes after IBI acknowledge

enumerator HAL_I3C_TGT_PAYLOAD_4_BYTE

0x00040000 4 additional data bytes after IBI ack 4 additional data bytes after IBI acknowledge

enum hal_i3c_activity_state_t

Advertised recent bus activity level (power/perf hint).

Encodes recent bus traffic level for power/performance heuristics. Targets can adjust internal low-power policies or clocking based on the advertised activity state. Higher numbers generally indicate more frequent transfers or reduced idle periods.

Values:

enumerator HAL_I3C_ACTIVITY_STATE_0

Controller on the bus activity state 0 Activity state 0

enumerator HAL_I3C_ACTIVITY_STATE_1

0x00100000 Controller on the bus activity state 1 Activity state 1

enumerator HAL_I3C_ACTIVITY_STATE_2

0x00200000 Controller on the bus activity state 2 Activity state 2

enumerator HAL_I3C_ACTIVITY_STATE_3

Controller on the bus activity state 3 Activity state 3

enum hal_i3c_reset_action_t

Scope of peripheral reset to apply.

Values:

enumerator HAL_I3C_RESET_ACTION_NONE

No reset action required No reset action required

enumerator HAL_I3C_RESET_ACTION_PARTIAL

0x00400000 Reset of some internal registers of the peripheral Reset some internal registers of the peripheral

enumerator HAL_I3C_RESET_ACTION_FULL

0x00800000 Reset all internal registers of the peripheral Reset all internal registers of the peripheral

enum hal_i3c_handoff_activity_state_t

Intended bus activity level immediately after controller handoff.

Advertised bus activity level the device intends to maintain immediately after it assumes Controller-Role (post handoff). Guides peers power management expectations. Higher states imply shorter idle windows and potentially higher average power draw.

Values:

enumerator HAL_I3C_HANDOFF_ACTIVITY_STATE_0

Activity state 0 after controllership handoff Activity state 0 after handoff

enumerator HAL_I3C_HANDOFF_ACTIVITY_STATE_1

0x00000001 Activity state 1 after controllership handoff Activity state 1 after handoff

enumerator HAL_I3C_HANDOFF_ACTIVITY_STATE_2

0x00000002 Activity state 2 after controllership handoff Activity state 2 after handoff

enumerator HAL_I3C_HANDOFF_ACTIVITY_STATE_3

Activity state 3 after controllership handoff Activity state 3 after handoff

enum hal_i3c_turnaround_time_tsco_t

Target device clock-to-valid-data timing class (tSCO capability).

Declares the device’s timing capability from the rising edge of SCL to valid data on SDA. Used during timing negotiation so the controller can honour the slowest participant. LESS_12NS indicates a faster device (tSCO <= 12 ns); GREATER_12NS requires relaxed sampling.

Values:

enumerator HAL_I3C_TURNAROUND_TIME_TSCO_LESS_12NS

clock-to-data turnaround time tSCO <= 12ns clock-to-data turnaround time tSCO <= 12ns

enumerator HAL_I3C_TURNAROUND_TIME_TSCO_GREATER_12NS

0x01000000 Clock-to-data Turnaround time clock-to-data turnaround time tSCO > 12ns clock-to-data turnaround time tSCO > 12ns

enum hal_i3c_max_speed_limitation_status_t

Max data speed limitation status (BCR bit 0).

Values:

enumerator HAL_I3C_MAX_SPEED_LIMITATION_DISABLED

No max data speed limitation BCR[0]=0: max speed limitation disabled

enumerator HAL_I3C_MAX_SPEED_LIMITATION_ENABLED

0x00000001 Max Data Speed Limitation Max data speed limitation BCR[0]=1: max speed limitation enabled

enum hal_i3c_ibi_req_status_t

IBI request status (BCR bit 1).

Values:

enumerator HAL_I3C_IBI_REQ_DISABLED

IBI request not supported (BCR1 = 0) BCR[1]=0: IBI request disabled

enumerator HAL_I3C_IBI_REQ_ENABLED

0x00000002 IBI Request capable IBI request supported (BCR1 = 1) BCR[1]=1: IBI request enabled

enum hal_i3c_ibi_payload_status_t

Ability to send data byte(s) with an IBI (BCR bit 2).

Values:

enumerator HAL_I3C_IBI_PAYLOAD_DISABLED

No data byte follows the accepted IBI BCR[2]=0: IBI payload disabled

enumerator HAL_I3C_IBI_PAYLOAD_ENABLED

0x00000004 IBI Payload additional Mandatory Data Byte A Mandatory data Byte (MDB) follows the accepted IBI BCR[2]=1: IBI payload enabled

enum hal_i3c_offline_capable_status_t

Offline capable status (BCR bit 3).

Values:

enumerator HAL_I3C_OFFLINE_CAPABLE_DISABLED

No Offline capable BCR[3]=0: offline not supported

enumerator HAL_I3C_OFFLINE_CAPABLE_ENABLED

0x00000008 Offline capable Offline capable BCR[3]=1: offline supported

enum hal_i3c_virtual_tgt_status_t

Virtual target support status (BCR bit 4).

Values:

enumerator HAL_I3C_VIRTUAL_TGT_DISABLED

Virtual target not supported (BCR4 = 0) BCR[4]=0: virtual target not supported

enumerator HAL_I3C_VIRTUAL_TGT_ENABLED

0x00000010 Virtual target support Virtual target supported (BCR4 = 1) BCR[4]=1: virtual target supported

enum hal_i3c_adv_capabilities_status_t

Advanced capabilities status (BCR bit 5).

Values:

enumerator HAL_I3C_ADV_CAPABILITIES_DISABLED

Advanced capabilities not supported (BCR5 = 0) BCR[5]=0: advanced capabilities disabled

enumerator HAL_I3C_ADV_CAPABILITIES_ENABLED

0x00000020 Advanced capabilities Advanced capabilities supported (BCR5 = 1) BCR[5]=1: advanced capabilities enabled

enum hal_i3c_ctrl_role_status_t

Target device Controller-Role status (BCR bit 5).

Values:

enumerator HAL_I3C_CTRL_ROLE_DISABLED

I3C target BCR[6]=0: Target device must not request Controller-Role handoff

enumerator HAL_I3C_CTRL_ROLE_ENABLED

0x00000040 Device Role shared during Dynamic Address Assignment I3C controller BCR[6]=1:Target device can request Controller-Role handoff

enum hal_i3c_ctrl_ibi_ack_status_t

Controller acknowledge policy for target IBI requests.

Values:

enumerator HAL_I3C_CTRL_IBI_ACK_DISABLED

Ctrl no acknowledge tgt IBI capable Controller NACKs the IBI requests from the target

enumerator HAL_I3C_CTRL_IBI_ACK_ENABLED

0x00010000 IBI Acknowledge from Target x Ctrl acknowledge tgt IBI capable Controller ACKs the IBI requests from the target

enum hal_i3c_ctrl_role_ack_status_t

Controller response status to a Controller-Role request from target device.

Values:

enumerator HAL_I3C_CTRL_ROLE_ACK_DISABLED

Ctrl no acknowledge tgt ctrl-role capable Controller NACK when receiving a Controller-Role request from the target device

enumerator HAL_I3C_CTRL_ROLE_ACK_ENABLED

0x00020000 Controller-role Acknowledge from Target x Ctrl acknowledge tgt ctrl-role capable Controller ACK when receiving a Controller-Role request from the target device

enum hal_i3c_ctrl_stop_transfer_status_t

Controller suspend/stop policy on IBI reception (SUSP bit).

Values:

enumerator HAL_I3C_CTRL_STOP_TRANSFER_DISABLED

Do not suspend: normal next control flow (restart/stop depends on CR) Do not auto STOP/flush on IBI completion

enumerator HAL_I3C_CTRL_STOP_TRANSFER_ENABLED

0x00080000 Suspended Transfer Suspend current transfer: emit STOP and flush C-FIFO/TX-FIFO after IBI Auto STOP + flush C-FIFO/TX-FIFO on IBI completion

enum hal_i3c_ctrl_ibi_payload_status_t

Controller IBI payload policy.

Values:

enumerator HAL_I3C_CTRL_IBI_PAYLOAD_DISABLED

No mandatory data byte follows the IBI acknowledgement Data follows the IBI ACK

enumerator HAL_I3C_CTRL_IBI_PAYLOAD_ENABLED

0x00040000 IBI Additional Data Enable A mandatory data byte follows the IBI acknowledgement No data follows the IBI ACK

enum hal_i3c_tgt_ibi_status_t

IBI capability from target point of view.

Values:

enumerator HAL_I3C_TGT_IBI_DISABLED

IBI is not supported by target device

enumerator HAL_I3C_TGT_IBI_ENABLED

IBI supported by target device

enum hal_i3c_tgt_ctrl_role_status_t

Controller-Role capability from target point of view.

Values:

enumerator HAL_I3C_TGT_CTRL_ROLE_DISABLED

Controller-Role is not supported by target device

enumerator HAL_I3C_TGT_CTRL_ROLE_ENABLED

Controller-Role is supported by target device

enum hal_i3c_target_detection_status_t

Target detection status during DAA procedure.

Values:

enumerator HAL_I3C_TGT_NOT_DETECTED

No target has been detected

enumerator HAL_I3C_TGT_DETECTED

A target has been detected

enum hal_i3c_handoff_delay_status_t

Handoff delay status.

Values:

enumerator HAL_I3C_HANDOFF_DELAY_DISABLED

Handoff delay is disabled

enumerator HAL_I3C_HANDOFF_DELAY_ENABLED

Handoff delay is enabled

enum hal_i3c_grp_addr_capability_status_t

Group address capability status.

Values:

enumerator HAL_I3C_GRP_ADDR_CAPABILITY_DISABLED

Group address capability is disabled

enumerator HAL_I3C_GRP_ADDR_CAPABILITY_ENABLED

Group address capability is enabled

enum hal_i3c_getmxds_format_t

GETMXDS CCC format and maximum read turnaround byte latency. Format 1 : No 3-byte MaxRdTurn (maximum read turnaround byte) is returned. Format 2 : 3-byte MaxRdTurn (maximum read turnaround byte) is returned.

Values:

enumerator HAL_I3C_GETMXDS_FORMAT_1

GETMXDS CCC format 1 is used, no MaxRdTurn field in response No 3-byte MaxRdTurn (maximum read turnaround byte).

enumerator HAL_I3C_GETMXDS_FORMAT_2_LSB

0x00000100 GETMXDS CCC format 2 is used, MaxRdTurn field in response, LSB = RDTURN[7:0] (<256 us) Target maximum read turnaround byte (RDTURN[7:0]) placed in the least-significant byte of the 3-byte MaxRdTurn (middle & MSB = 0)

enumerator HAL_I3C_GETMXDS_FORMAT_2_MID

0x00000200 GETMXDS CCC format 2 is used, MaxRdTurn field in response, middle byte = RDTURN[7:0] (256 us to 65 ms) Target maximum read turnaround byte (RDTURN[7:0]) placed in the middle byte of the 3-byte MaxRdTurn (LSB & MSB = 0)

enumerator HAL_I3C_GETMXDS_FORMAT_2_MSB

GETMXDS CCC format 2 is used, MaxRdTurn field in response, MSB = RDTURN[7:0] (65 ms to 16 s) Target maximum read turnaround byte (RDTURN[7:0]) placed in the most-significant byte of the 3-byte MaxRdTurn (LSB & MID = 0)

enum hal_i3c_hot_join_status_t

Hot-Join status.

Values:

enumerator HAL_I3C_HOT_JOIN_DISABLED

Hot-Join is disabled

enumerator HAL_I3C_HOT_JOIN_ENABLED

Hot-Join is enabled

enum hal_i3c_high_keeper_sda_status_t

SDA high keeper enable state.

Values:

enumerator HAL_I3C_HIGH_KEEPER_SDA_DISABLED

The controller SDA high keeper is disabled

enumerator HAL_I3C_HIGH_KEEPER_SDA_ENABLED

The controller SDA high keeper is enabled

enum hal_i3c_reset_pattern_status_t

Reset Pattern status.

Values:

enumerator HAL_I3C_RESET_PATTERN_DISABLED

Standard STOP condition emitted at the end of a frame

enumerator HAL_I3C_RESET_PATTERN_ENABLED

Reset pattern is inserted before the STOP condition of any emitted frame

enum hal_i3c_tgt_read_mdb_status_t

Pending mandatory data bytes notification with GETCAPR.

Values:

enumerator HAL_I3C_PENDING_READ_MDB_DISABLED

No support of pending read notification via the IBI MDB[7:0] value Pending read mandatory data bytes is disabled

enumerator HAL_I3C_PENDING_READ_MDB_ENABLED

0x00004000 IBI Request with Mandatory Data Byte Support of pending read notification via the IBI MDB[7:0] value Pending read mandatory data bytes is enabled

enum hal_i3c_t

HAL I3C instance.

Values:

enumerator HAL_I3C1

Peripheral instance I3C1

struct hal_i3c_ccc_desc_t

#include <stm32c5xx_hal_i3c.h>

Software descriptor for direct or broadcast CCC frame.

Public Members

uint8_t tgt_addr

7-bit dynamic or static target address placed on the bus. For broadcast CCC the broadcast address (7’h7E) is used.

uint8_t ccc

7-bit CCC opcode (direct or broadcast) per I3C specification section CCC. Distinguishes the command semantic.

uint32_t data_size_byte

Number of data bytes associated with the CCC (including defining byte when present). Set to 0 if no data phase is required.

hal_i3c_direction_t direction

Data phase direction: READ or WRITE. Must be WRITE for broadcast CCC. Direct CCC can be READ or WRITE depending on opcode definition.

struct hal_i3c_bcr_t

#include <stm32c5xx_hal_i3c.h>

Decoded BCR capability/status bits for a target.

Populated from ENTDAA payload; each field mirrors one BCR capability bit or status for later use in controller configuration and application policy.

Public Members

hal_i3c_max_speed_limitation_status_t max_data_speed_limitation

HAL_I3C_MAX_SPEED_LIMITATION_ENABLED => target cannot operate at highest bus speed. HAL_I3C_MAX_SPEED_LIMITATION_DISABLED => no speed limitation declared.

hal_i3c_ibi_req_status_t ibi_request_capable

HAL_I3C_IBI_REQ_ENABLED => target can initiate an In-Band Interrupt (IBI) to request service. HAL_I3C_IBI_REQ_DISABLED => target never issues IBI requests.

hal_i3c_ibi_payload_status_t ibi_payload

Capability to append one data byte (or more depending on config) after IBI acceptance to qualify the interrupt source.

hal_i3c_offline_capable_status_t offline_capable

Target can temporarily not respond to bus commands. HAL_I3C_OFFLINE_CAPABLE_ENABLED => controller must tolerate silent periods. HAL_I3C_OFFLINE_CAPABLE_DISABLED => target expected to respond consistently.

hal_i3c_virtual_tgt_status_t virtual_target_support

Identifies a virtual (composite / logical) target rather than a discrete physical device.

hal_i3c_adv_capabilities_status_t advanced_capabilities

Target implements optional advanced I3C capabilities beyond the baseline feature set (e.g. controller role hand-off readiness).

hal_i3c_ctrl_role_status_t ctrl_role

Target Controller-Role. HAL_I3C_CTRL_ROLE_ENABLED => target can request a Controller-Role handoff during Dynamic Address Assignment (DAA) or via a Controller-Role (CR) request sequence. HAL_I3C_CTRL_ROLE_DISABLED => target cannot request a Controller-Role handoff and any such attempt is ignored by higher-level policy.

struct hal_i3c_pid_t

#include <stm32c5xx_hal_i3c.h>

Decoded Provisioned ID (PID) fields.

Public Members

uint16_t mipi_manuf_id

MIPI-assigned manufacturer ID (PID bits [47:33]).

uint8_t id_type_sel

PID type selector / IDTSEL (format discriminator, PID bit [32]).

uint16_t part_id

Vendor part identifier (PID bits [31:21]) distinguishing device model/revision.

uint8_t mipi_id

Instance ID within the part family (PID bits [20:17]) for multiple identical targets.

struct hal_i3c_private_desc_t

#include <stm32c5xx_hal_i3c.h>

Software descriptor for a private frame (I3C or legacy I2C).

Public Members

uint8_t tgt_addr

7-bit dynamic or static target address placed on the bus

uint32_t data_size_byte

Number of data bytes to transmit or receive in the data phase. Set to 0 for pure header-only operations (rare).

hal_i3c_direction_t direction

Data direction for the frame: WRITE sends bytes from controller to target, READ requests bytes from target.

struct hal_i3c_transfer_ctx_t

#include <stm32c5xx_hal_i3c.h>

Aggregated multi-frame transfer context (descriptors + buffers).

Note

All frames aggregated in a transfer context must share the same high-level transfer mode hal_i3c_transfer_mode_t

Public Members

uint32_t * p_tc_data

Pointer to transmit control descriptor words populated by HAL_I3C_CTRL_BuildTransferCtxPrivate or HAL_I3C_CTRL_BuildTransferCtxCCC

uint32_t tc_size_word

Control buffer size depends on the transfer mode and the number of aggregated frames. The helper HAL_I3C_GET_CTRL_BUFFER_SIZE_WORD can be used to get it.

const uint8_t * p_tx_data

Pointer to concatenated transmit payload(s) for all frames needing TX phase. Frames reference offsets implicitly in the order they are executed.

uint32_t tx_size_byte

Total number of transmit bytes across all frames. Set to 0 if no TX phase.

uint8_t * p_rx_data

Pointer to receive buffer storing concatenated RX data of frames with read phase.

uint32_t rx_size_byte

Total expected receive bytes across all frames. Set to 0 if no RX phase.

hal_i3c_transfer_mode_t transfer_mode

Transfer mode bitfield (HAL_I3C_PRIVATE_xxx or HAL_I3C_CCC_xxx) governing arbitration, stop/restart behavior, and message type.

uint32_t nb_tx_frame

Number of frames that have a transmit portion (debug / parameter checking aid).

struct hal_i3c_ctrl_config_t

#include <stm32c5xx_hal_i3c.h>

Controller timing configuration.

Pre-computed I3C_TIMINGR0 / I3C_TIMINGR1 register values (prescalers + timing segments) generated by tooling (CubeMX2 / helpers). Used verbatim by HAL_I3C_CTRL_SetConfig(). Keep the pair consistent.

Public Members

uint32_t timing_reg0

Encoded I3C_TIMINGR0 register value (prescalers + low/high periods for SDR/legacy). Must be generated to satisfy bus frequency constraints of all attached targets.

uint32_t timing_reg1

Encoded I3C_TIMINGR1 register value (additional setup/hold segments and filter tuning). Derived together with timing_reg0; keep the pair consistent.

struct hal_i3c_tgt_config_t

#include <stm32c5xx_hal_i3c.h>

Target timing configuration.

Pre-computed I3C_TIMINGR1 register values (target turnaround / filtering) generated by tooling (CubeMX2 / helpers). Used verbatim by HAL_I3C_TGT_SetConfig().

Public Members

uint32_t timing_reg1

Encoded I3C_TIMINGR1 register value used when peripheral operates as target to meet bus timing constraints.

struct hal_i3c_tgt_config_payload_entdaa_t

#include <stm32c5xx_hal_i3c.h>

ENTDAA advertised capability payload (target identity fields for BCR/DCR/PID synthesis).

Public Members

uint8_t identifier

Target characteristic ID (MIPI named reference DCR). This parameter must be a number between Min_Data=0x00 and Max_Data=0xFF.

uint8_t mipi_identifier

Bits [12-15] of the 48 bit provisioned ID (MIPI named reference PID). This parameter must be a number between Min_Data=0x0 and Max_Data=0xF.

hal_i3c_ctrl_role_status_t ctrl_role

Target can request Controller-Role handoff (BCR bit)

hal_i3c_ibi_payload_status_t ibi_payload

Target can send data after an acknowledged IBI (BCR bit)

hal_i3c_max_speed_limitation_status_t max_data_speed_limitation

Target max data speed limitation (BCR bit)

struct hal_i3c_ctrl_fifo_config_t

#include <stm32c5xx_hal_i3c.h>

Controller FIFOs thresholds and enable selection.

Public Members

hal_i3c_rx_fifo_threshold_t rx_fifo_threshold

I3C Rx FIFO threshold level

hal_i3c_tx_fifo_threshold_t tx_fifo_threshold

I3C Tx FIFO threshold level

hal_i3c_ctrl_fifo_t ctrl_fifo

I3C control and status activation

struct hal_i3c_tgt_fifo_config_t

#include <stm32c5xx_hal_i3c.h>

Target FIFOs thresholds configuration.

Public Members

hal_i3c_rx_fifo_threshold_t rx_fifo_threshold

I3C Rx FIFO threshold level

hal_i3c_tx_fifo_threshold_t tx_fifo_threshold

I3C Tx FIFO threshold level

struct hal_i3c_tgt_ibi_config_t

#include <stm32c5xx_hal_i3c.h>

Target IBI payload size & pending-read notification configuration.

Public Members

hal_i3c_tgt_payload_size_t ibi_payload_size_byte

I3C target payload data size

hal_i3c_tgt_read_mdb_status_t pending_read_mdb

Transmission of a mandatory data bytes indicating a pending read notification for GETCAPR CCC command

struct hal_i3c_tgt_getmxds_config_t

#include <stm32c5xx_hal_i3c.h>

Target GETMXDS response parameters (format, activity, timing).

Public Members

hal_i3c_getmxds_format_t getmxds_format

GETMXDS CCC Format

hal_i3c_handoff_activity_state_t ctrl_handoff_activity

I3C Target activity when becoming controller

hal_i3c_turnaround_time_tsco_t data_turnaround_duration

I3C target clock-to-data turnaround time

uint8_t max_read_turnaround

Target maximum read turnaround byte (RDTURN[7:0]). This parameter must be a number between Min_Data=0x00 and Max_Data=0xFF

struct hal_i3c_ctrl_device_config_t

#include <stm32c5xx_hal_i3c.h>

Target device configuration from controller point of view. Store in DEVRx registers.

Public Members

uint8_t device_index

Index value of the target device in the DEVRx register. This parameter must be a number between Min_Data=0 and Max_Data=3

uint8_t tgt_dynamic_addr

Dynamic address of the target device. This parameter must be a number between Min_Data=0x00 and Max_Data=0x7F

hal_i3c_ctrl_ibi_ack_status_t ibi_ack

Controller ack when receiving an IBI from the target device

hal_i3c_ctrl_ibi_payload_status_t ibi_payload

Target IBI payload after an IBI. Information retrieved from the target device during broadcast ENTDAA or direct GETBCR CCC

hal_i3c_ctrl_role_ack_status_t ctrl_role_req_ack

Controller ack when receiving a Controller-Role request from the target device

hal_i3c_ctrl_stop_transfer_status_t ctrl_stop_transfer

Controller stops transfer after receiving an IBI from the target device

struct hal_i3c_entdaa_payload_t

#include <stm32c5xx_hal_i3c.h>

ENTDAA combined BCR/DCR/PID payload fields.

Public Members

hal_i3c_bcr_t bcr

Bus characteristics register

uint32_t dcr

Device characteristics register

hal_i3c_pid_t pid

Provisioned ID

struct hal_i3c_ccc_info_t

#include <stm32c5xx_hal_i3c.h>

Target/Controller gets the Common Command Code (CCC) information updated after notifications.

CCC Notification	Updated fields in p_ccc_info
HAL_I3C_TGT_NOTIFICATION_DAU	dynamic_addr, dynamic_addr_valid
HAL_I3C_TGT_NOTIFICATION_SETMWL	max_write_data_size_byte
HAL_I3C_TGT_NOTIFICATION_SETMRL	max_read_data_size_byte
HAL_I3C_TGT_NOTIFICATION_RSTACT	reset_action
HAL_I3C_TGT_NOTIFICATION_ENTAS_X	activity_state
HAL_I3C_TGT_NOTIFICATION_ENEC_DISEC	hot_join_allowed, in_band_allowed, ctrl_role_allowed
HAL_I3C_CTRL_NOTIFICATION_IBI	ibi_cr_tgt_addr, ibi_tgt_nb_payload, ibi_tgt_payload
HAL_I3C_CTRL_NOTIFICATION_CR	ibi_cr_tgt_addr

Public Members

uint32_t dynamic_addr_valid

I3C target dynamic address validity (updated during ENTDAA/RSTDAA/SETNEWDA CCC) This parameter=1U after an ENTDAA or a SETNEWDA This parameter=0U after a RSTDAA

uint32_t dynamic_addr

I3C target dynamic address (updated during ENTDAA/RSTDAA/SETNEWDA CCC) This parameter can be between Min_Data=0 and Max_Data=0x7F.

uint32_t max_read_data_size_byte

Maximum read data length (in byte) that the target advertises to the Controller. Updated during SETMWL CCC. This parameter can be between Min_Data=0 and Max_Data=0xFFFF.

uint32_t max_write_data_size_byte

Maximum write data length (in byte) that the target guarantees it can accept. Updated during SETMRL CCC. This parameter can be between Min_Data=0 and Max_Data=0xFFFF.

hal_i3c_reset_action_t reset_action

I3C target reset action level (updated during RSTACT CCC)

hal_i3c_activity_state_t activity_state

I3C target activity state (updated during ENTASx CCC)

uint32_t hot_join_allowed

I3C target Hot-Join (updated during ENEC/DISEC CCC) This parameter can be allowed=1U or not allowed=0U

uint32_t in_band_allowed

I3C target in-band interrupt (updated during ENEC/DISEC CCC) This parameter can be allowed=1U or not allowed=0U

uint32_t ctrl_role_allowed

I3C Target Controller-Role request permission (updated during ENEC/DISEC CCC). Value 1U => Target can request Controller role; 0U => not permitted.

uint32_t ibi_cr_tgt_addr

I3C controller receives target address during IBI or Controller-Role request event This parameter can be between Min_Data=0 to Max_Data=0x3F

uint32_t ibi_tgt_nb_payload

I3C controller gets the number of data payload bytes after an IBI event This parameter can be between Min_Data=0 to Max_Data=0x7

uint32_t ibi_tgt_payload

I3C controller receives IBI payload after an IBI event Content of register is filled in Little Endian:

• The MSB corresponds to the last IBI data byte,

• LSB corresponds to first IBI data byte. This parameter can be between Min_Data=0 to Max_Data=0xFFFFFFFF

struct hal_i3c_handle_s

#include <stm32c5xx_hal_i3c.h>

I3C handle structure definition.

Public Members

hal_i3c_t instance

Peripheral instance

hal_i3c_mode_t mode

Communication mode

uint32_t listen

Listen mode

volatile hal_i3c_state_t global_state

Communication state

volatile uint32_t last_error_codes

Errors limited to the last process This parameter can be a combination of Error code definition

const uint32_t * p_tc_data

Transmit Control descriptor buffer

const uint8_t * p_tx_data

Transmit data buffer

uint8_t * p_rx_data

Receive data buffer

uint32_t tc_count_word

Remaining control descriptor to transmit in word

uint32_t data_size_byte

Data size to transmit or receive in byte

uint32_t tx_count_byte

Remaining data to transmit in byte

uint32_t rx_count_byte

Remaining data to receive in byte

hal_status_t ( * p_isr_func ) ( hal_i3c_handle_t * hi3c , uint32_t it_masks )

Dynamically selected IRQ handler for the current transfer/use case. Updated at operation start to route interrupts to the appropriate optimized routine

void ( * p_tx_func ) ( hal_i3c_handle_t * hi3c )

Transmit function pointer

void ( * p_rx_func ) ( hal_i3c_handle_t * hi3c )

Receive function pointer

hal_dma_handle_t * hdma_tc

Transmit Control descriptor DMA handle (Controller side only)

hal_dma_handle_t * hdma_tx

Transmit data DMA handle

hal_dma_handle_t * hdma_rx

Receive data DMA handle

const void * p_user_data

User data pointer

hal_os_semaphore_t semaphore

OS semaphore

hal_i3c_notify_cb_t p_notify_cb

Target/Controller asynchronous events callback

hal_i3c_cb_t p_error_cb

Target/Controller error callback

hal_i3c_cb_t p_abort_cplt_cb

Target/Controller abort complete callback

hal_i3c_cb_t p_ctrl_daa_cplt_cb

Controller Dynamic Address Assignment completed callback

hal_i3c_cb_t p_ctrl_transfer_cplt_cb

Controller multiple direct CCC, I3C private or I2C transfer completed callback

hal_i3c_req_dyn_addr_cb_t p_ctrl_tgt_req_dyn_addr_cb

Controller gets target dynamic address request during DAA process

hal_i3c_cb_t p_tgt_tx_cplt_cb

Target private data transmit transfer completed callback

hal_i3c_cb_t p_tgt_rx_cplt_cb

Target private data receive transfer completed callback

hal_i3c_tgt_hot_join_cb_t p_tgt_hot_join_cb

Target Hot-Join callback

Controller notification ID

STM32C562xx STM32C5A3xx STM32C542xx

group I3C_CTRL_NOTIFICATION

Defines

HAL_I3C_CTRL_NOTIFICATION_IBI LL_I3C_IER_IBIIE

Receive IBI

HAL_I3C_CTRL_NOTIFICATION_CR LL_I3C_IER_CRIE

Controller-Role request

HAL_I3C_CTRL_NOTIFICATION_HJ LL_I3C_IER_HJIE

Hot-Join

HAL_I3C_CTRL_NOTIFICATION_ALL ( LL_I3C_IER_IBIIE | LL_I3C_IER_CRIE | LL_I3C_IER_HJIE )

All notif

Target notification ID

STM32C562xx STM32C5A3xx STM32C542xx

group I3C_TGT_NOTIFICATION

Defines

HAL_I3C_TGT_NOTIFICATION_GETACCCR LL_I3C_IER_CRUPDIE

Controller-Role hand-off, direct GETACCR CCC

HAL_I3C_TGT_NOTIFICATION_IBIEND LL_I3C_IER_IBIENDIE

IBI end process

HAL_I3C_TGT_NOTIFICATION_DAU LL_I3C_IER_DAUPDIE

Dynamic Address Update: ENTDAA, RSTDAA or SETNEWDA. To discriminate RSTDAA from other CCC, call HAL_I3C_GetCCCInfo() and check the field dynamic_addr_valid of hal_i3c_ccc_info_t structure

HAL_I3C_TGT_NOTIFICATION_GET_X LL_I3C_IER_GETIE

Any direct GETxxx CCC

HAL_I3C_TGT_NOTIFICATION_GET_STATUS LL_I3C_IER_STAIE

Get status command, direct GETstatus CCC

HAL_I3C_TGT_NOTIFICATION_SETMWL LL_I3C_IER_MWLUPDIE

Max write length update, direct SETMWL CCC

HAL_I3C_TGT_NOTIFICATION_SETMRL LL_I3C_IER_MRLUPDIE

Max read length update, direct SETMRL CCC

HAL_I3C_TGT_NOTIFICATION_RSTACT LL_I3C_IER_RSTIE

Reset pattern, broadcast or direct RSTACT CCC

HAL_I3C_TGT_NOTIFICATION_ENTAS_X LL_I3C_IER_ASUPDIE

Activity state update, direct or broadcast ENTASx

HAL_I3C_TGT_NOTIFICATION_ENEC_DISEC LL_I3C_IER_INTUPDIE

Receive a direct or broadcast ENEC/DISEC CCC

HAL_I3C_TGT_NOTIFICATION_WKP LL_I3C_IER_WKPIE

Wakeup

HAL_I3C_TGT_NOTIFICATION_DEFTGTS ( LL_I3C_IER_DEFIE | LL_I3C_IER_RXFNEIE )

Broadcast DEFTGTS CCC

HAL_I3C_TGT_NOTIFICATION_DEFGRPA ( LL_I3C_IER_GRPIE | LL_I3C_IER_RXFNEIE )

Group addressing, broadcast DEFGRPA CCC

HAL_I3C_TGT_NOTIFICATION_ALL ( \ HAL_I3C_TGT_NOTIFICATION_GETACCCR | \ HAL_I3C_TGT_NOTIFICATION_IBIEND | \ HAL_I3C_TGT_NOTIFICATION_DAU | \ HAL_I3C_TGT_NOTIFICATION_GET_X | \ HAL_I3C_TGT_NOTIFICATION_GET_STATUS | \ HAL_I3C_TGT_NOTIFICATION_SETMWL | \ HAL_I3C_TGT_NOTIFICATION_SETMRL | \ HAL_I3C_TGT_NOTIFICATION_RSTACT | \ HAL_I3C_TGT_NOTIFICATION_ENTAS_X | \ HAL_I3C_TGT_NOTIFICATION_ENEC_DISEC | \ HAL_I3C_TGT_NOTIFICATION_WKP | \ HAL_I3C_TGT_NOTIFICATION_DEFTGTS | \ HAL_I3C_TGT_NOTIFICATION_DEFGRPA )

All notifications